home *** CD-ROM | disk | FTP | other *** search
/ MacAddict 117 / MacAddict 117.dmg / Software / Development / REALbasic 2006 Release 1 (demo).dmg / REALbasic 2006 Release 1 / Read Me / IDE Scripting Read Me.txt < prev    next >
Encoding:
Text File  |  2006-01-05  |  8.5 KB  |  197 lines
  1. Controlling the REALbasic IDE Through RBScript
  2.  
  3. Introduction
  4. In REALbasic 2005R5 or later, you can automate certain tasks in the 
  5. IDE by writing and executing RBScript code.  Possible applications 
  6. include automating the build process, analyzing source code, and 
  7. inserting or modifying source text.
  8.  
  9. To get started, use the "New IDE Script" command under the File menu. 
  10. This presents a simple script editor.  Try the following script:
  11.  
  12.    Dim i As Integer
  13.    For i = 3 DownTo 1
  14.      Print str(i) + "..."
  15.    Next
  16.    Print "Lift-off!"
  17.  
  18. Click the Run button, and you should see a MsgBox appear with the 
  19. contents of each Print command.
  20.  
  21. Of course this is a useless example.  Here's a more useful one, which 
  22. sets the ShortVersion to "1.0J", sets the build language to Japanese, 
  23. and then builds a Mac version of the application:
  24.  
  25.    PropertyValue("App.ShortVersion") = "1.0J"
  26.    BuildWin32 = False
  27.    BuildMacMachO = True
  28.    BuildLanguage = "Japanese"
  29.    DoCommand "BuildApp"
  30.  
  31. You may be wondering how to know all the magic words, like 
  32. "BuildMacMachO" in the example above.  There are two sources for that 
  33. knowledge: one is the reference material at the end of this document. 
  34. The other is to simply record yourself doing the task manually.
  35.  
  36.  
  37. Recording
  38. When you click the Record button in a script editor, the editor goes 
  39. into "recording" mode (and the button stays down as long as it's in 
  40. this mode).  While recording, any scriptable action you do in the IDE 
  41. is added to the editor as RBScript code.  You then return to the 
  42. script editor, stop the recording (by clicking Record again), and 
  43. neaten up the script -- deleting unimportant commands, changing 
  44. constants to variables as required, and so on.  The example above was 
  45. made in exactly this way.
  46.  
  47. Script recording is a powerful feature for automating repetitive 
  48. tasks; it does most of the work for you, freeing you from having to 
  49. know the syntax for most actions.
  50.  
  51.  
  52. Command-Line Interface
  53. IDE Scripts can run command-line tools via the DoShellCommand, 
  54. documented below.  In addition, there is a command-line tool which 
  55. can drive the IDE via IDE scripts.  This is called "rbidescript" and 
  56. is provided and documented separately.
  57.  
  58.  
  59. Script Functionality - Overview
  60. Your scripts have access to all the standard functions in RBScript, 
  61. including string manipulation, math, and so on.  See the RBScript 
  62. entry in the language reference for a detailed list.  Note that the 
  63. standard Print command displays a message box, and the Input command 
  64. gets input via a simple modal dialog.  As in any RBScript, you can 
  65. also write methods, classes, or modules within your script if needed 
  66. to help organize your code (though many scripts will be so simple as 
  67. to not need them).
  68.  
  69. In addition to the standard RBScript functions, there are additional 
  70. functions and properties which are defined just for IDE scripts, 
  71. which manipulate projects in the IDE in various ways.  These 
  72. functions are detailed below.  Most of them operate on the frontmost 
  73. project window, and on the current project item or method within that 
  74. window.  However, there are ways to change the current window or 
  75. location for cases where your script needs to act upon a particular 
  76. item.
  77.  
  78. Most of the things your script can do fall into one of the following 
  79. categories:
  80.   - Changing the context (SelectWindow, Location)
  81.   - Changing project item properties (PropertyValue)
  82.   - Changing build settings (BuildLanguage, BuildLinux, etc.)
  83.   - Executing commands, as if chosen from a toolbar or menu (DoCommand)
  84.   - Interacting with the user (Print, Input, Beep, Speak)
  85.   - Inspecting or changing source code (Text, SelText, SelStart, SelLength)
  86.  
  87. There are also a few utility functions that don't fit neatly into the 
  88. above categories (e.g., Clipboard).  A complete reference follows.
  89.  
  90.  
  91. Script Functionality - Reference
  92.  
  93. Beep: plays the system beep.
  94.  
  95. BuildLanguage as String: gets or sets the current build language.
  96.  
  97. BuildLinux as Boolean: gets or sets whether the project builds for Linux.
  98.  
  99. BuildMacClassics Boolean: gets or sets whether to build a classic Mac app.
  100.  
  101. BuildMacMachO as Boolean: gets or sets whether to build a Mach-O Mac app.
  102.  
  103. BuildMacPEF as Boolean: gets or sets whether to build a carbon PEF app.
  104.  
  105. BuildRegion as String: gets or sets the region code to be used in built apps.
  106.  
  107. BuildWin32 as Boolean: gets or sets whether to build a Windows app.
  108.  
  109. Clipboard as String: gets or sets the content of the copy/paste buffer.
  110.  
  111. DoCommand( cmdName as String ): Executes a command, as if the user 
  112. had pressed the corresponding toolbar button or selected a menu item. 
  113. Every such command in the IDE has a unique name which is used as the 
  114. argument for DoCommand.  To find the name of a particular command, 
  115. use the script recording feature.
  116.  
  117. DoShellCommand( cmd as String, timeOut as Integer=3000 ) as String: 
  118. Executes a shell command.  The shell environment is set up with the 
  119. following variables: IDE_PATH to point to the directory containing 
  120. the IDE; PROJECT_PATH to point to the directory containing the 
  121. project in the frontmost window; and PROJECT_FILE to point to the 
  122. actual project file.  The command is executed in synchronous 
  123. (blocking) mode, and returns any output as the result.
  124.  
  125. EndOfLine as String: returns the default line ending for the platform 
  126. you're running on.  This is also the line separator used in source 
  127. code text (e.g. that returned by Text and SelText).
  128.  
  129. Location as String: gets or sets the current location in the project, 
  130. as shown in the Location item of the main toolbar.  A script can use 
  131. this both to see its current context, and to navigate to some other 
  132. part of the project.
  133.  
  134. OpenFile( path as String ): attempts to open a REALbasic document 
  135. (e.g. project file) at the given path, which may be either a native 
  136. or a shell path.
  137.  
  138. ProjectItem as String: returns the name of the current project item, 
  139. i.e. the project item that is currently being edited, or that is 
  140. selected in the Project tab.
  141.  
  142. PropertyValue( propName as String ) as String: gets or sets the value 
  143. of a project itme property.  The propName argument may be just the 
  144. property name, in which case the property is found on the current 
  145. project item; or it may be the name of a project item plus the 
  146. property name, separated by a dot.  You may also use the special 
  147. keyword "App" to refer to the blessed Application subclass, even if 
  148. that is not actually named App.  The following are all valid property 
  149. references: "Width", "Window1.Width", "App.MajorVersion".
  150.  
  151. RunStript( scriptName as String ): Runs a script with the given name, 
  152. found in the Scripts folder (either next to the IDE or next to the 
  153. frontmost project file).  Note that due to a bug in RBScript, this 
  154. may currently crash the IDE.  We hope to have that fixed soon.
  155.  
  156. SelectWindow( windowTitle as String ): Brings a window to the front, 
  157. specified by its title.  If there is more than one window with the 
  158. given title, the one closest to the front is the one activated.
  159.  
  160. SelectWindow( index as Integer ): Brings a window to the front by its 
  161. current index in the Window list (see the WindowCount and WindowTitle 
  162. functions).
  163.  
  164. SelLength as Integer: gets or sets the length (in characters) of the 
  165. current selection in the current code editor, if any.
  166.  
  167. SelStart as Integer: gets or sets the offset of the selection (or 
  168. insertion point) in the current code editor.
  169.  
  170. SelText as String: gets or sets the selected text in the current code 
  171. editor.  Note that after assigning to SelText, the selection will be 
  172. empty and positioned right after the inserted text.  (This is the 
  173. same behavior as EditField.SelText.)
  174.  
  175. Speak( text as String, interrupt as Boolean=False ): Speaks the given 
  176. text via the system speech synthesis engine.  If interrupt = True, 
  177. then it interrupts any previous speech; otherwise it waits for 
  178. previous speech to finish.  This is the same behavior as the built-in 
  179. Speak command in REALbasic.
  180.  
  181. Sublocations( baseLocation as String ): Returns all the locations 
  182. within the given base location, as a space-delimited string.  For 
  183. example, if baseLocation is "App", then this might return 
  184. "App.Activate App.CancelClose App.Close" (and so on).  The set of 
  185. locations returned should be the same ones suggested by 
  186. autocompletion in the Location field within the IDE. If baseLocation 
  187. is an empty string, then this returns the set of project items in the 
  188. frontmost project.
  189.  
  190. Text as String: gets or sets the entire text of the current code editor.
  191.  
  192. WindowCount as Integer: returns the number of windows in the IDE.
  193.  
  194. WindowTitle( index as Integer ) as String: returns the title of a 
  195. window indicated by its current index in the window list.  An index 
  196. of 0 means the frontmost window.
  197.